Workbench Design/WB Collection.iso/workbench werkzeuge/disk & file tools/archandler/archandler_guide

Amigaguide Document | 1996-04-07 | 21KB | 479 lines

@database ARCHandler
@$VER: ARCHandler.guide 37.40 (6.7.94)
@(C) Rafael D'Halleweyn
@author Rafael D'Halleweyn
@index index
@node main "ARCHandler 1.0a"
@prev main
@next main
                              @{b}ARCHandler 1.0a@{ub}
                             ================
            ARCHandler is Copyright
 1994 Rafael D'Halleweyn.
                           All rights reserved.
                          @{"       Disclaimer      " link disclaimer}
                          @{"    Shareware Notice   " link shareware}
                          @{"      Introduction     " link introduction}
                          @{"      Requirements     " link requirements}
                          @{"        Starting       " link starting}
                          @{"         Using         " link using}
                          @{" Technical Information " link techno}
                          @{"        History        " link history}
                          @{"       The author      " link author}
                       When I'm sad she comes to me
                          with a thousand smiles
                           she gives to me free
                   It's alright, it's alright she says,
                      Take anything you want from me,
                                 anything.
                                                Jimi Hendrix
@endnode
@node disclaimer "ARCHandler: Disclaimer"
@prev disclaimer
@next shareware
  @{b}@{u}Disclaimer@{ub}@{uu}
With  this  document  I  make  no  warranties  or  representations,  either
expressed  or  implied,  with  respect to the program described herein. The
program  and  the  information presented herein is being supplied on an `as
is'  basis  and  is  expressly subject to change without notice. The entire
risk  as to the use of the program and the information presented is assumed
by the user. In no event will I be liable for direct, indirect, incidental,
or consequential damages resulting from any claim arising out of the use of
the  program  or  the  information  presented  herein,  even if I have been
advised of the possibilities of such damages.
@endnode
@node shareware "ARCHandler: Shareware Notice"
@prev disclaimer
@next introduction
  @{b}@{u}ARCHandler is Shareware@{ub}@{uu}
This package is released as shareware. This means you can copy it freely as
long  as  you  don't ask any money for it, except perhaps a nominal fee for
copying.  If  you  like  and use this package on a regular base, you should
send  @{"me" link author}  a contribution of 500 BEF or USD 15. Send money by International
Money  Order,  EuroCheck (in BEF!) or Cash.
The  package  is  Copyright
 Rafael D'Halleweyn, All Rights Reserved. The
author  reserves the right to change the status of this package whenever he
finds it appropriate.
This  package  should  not  be  spread  in  any  other form than an LhA (or
equivalent)  archive  and  all  parts  of it should be spread together. The
package  may  not  be  altered in any way and cannot be used for commercial
purposes  without  the  prior written permission of the author. The archive
should contain the following files:
      ARCHandler (dir)
          C (dir)
            FlushARC
            MountListEntry
          L (dir)
            arc-handler
          S (dir)
            MountList-header
            WhichLhA
        ARC
        ARC.info
        ARCHandler.guide
        ARCHandler.guide.info
        Install
        Install.info
        ReadmeQuick
        ReadmeQuick.info
    ARCHandler.info
The   installation-script  (`Install')  and  the  extra  commands  it  uses
(`MountListEntry')  are  also  copyrighted  and  can't be used in any other
project/archive without the prior written permission of the author.
@endnode
@node introduction "ARCHandler: Introduction"
@prev shareware
@next requirements
  @{b}@{u}Introduction to the ARCHandler@{ub}@{uu}
@{"Archives" link archive}  (such  as  @{"LhA" link lha}  , Zip, Zoo, Tar, ...) are very easy to store and
move  large  amounts  of  files.  However,  if  you  wish  to use the files
contained  in  the  archive  you  always  have  to extract the files first.
Secondly,  to  easily  browse  through the archive, you have to extract the
whole archive.
Wouldn't  it  be  easier if you could treat archives just like directories:
move to a directory, look which files are in the directory and possibly use
one of those files.
I have already heard a lot of suggestions in this direction, so the idea is
neither  mine nor is it original. But I've never seen an implementation, so
I tried to make my own and this is the result.
Currently the ARCHandler only supports @{"lha" link lha}-archives.
@endnode
@node archive "What is an archive?"
@prev archive
@next archive
In  this  text the word @{i}archive @{ui}is used to indicated a group of files, that
are  stored in one big file, possibly also containing the file-structure of
the original (directories) and maybe using compression to store the files.
@{i}Archives @{ui}are mainly used to move large amounts of data from one computer to
another  (via  disk/modem/ftp/...).  @{i}Archives @{ui}are also an easy way to store
that data.
The ARCHandler currently only supports @{"lha" link lha}-archives.
@endnode
@node lha "What is an lha-archive?"
@prev lha
@next lha
LhA  is  probably  the  most widely used archiver on the Amiga. It uses the
Lempel-Ziv-Huffman (LZH) compression scheme to reduce archive size. Several
other  LZH-archives  exist for the Amiga (LhArcA, LhArc, LZ, LhEx, ...) and
for UNIX and MS-DOS machines.
@endnode
@node requirements "ARCHandler: Requirements"
@prev introduction
@next starting
  @{b}@{u}Requirements to use the ARCHandler@{ub}@{uu}
ARCHandler  currently requires an Amiga running Workbench/Kickstart 2.04 or
higher.  You  also  need  the  LhA  command  (
  Stefan  Boberg),  both the
registered and evaluation version should work.
ARCHandler  currently also needs the PIPE-device. If you didn't change your
Workbench-partition  after Workbench-installation this should be no problem
(otherwise you might want to add a `Mount PIPE:' to your User-Startup).
To test the handler, a few lha-archives can also be very handy :).
@endnode
@node starting "ARCHandler: Starting"
@prev requirements
@next using
  @{b}@{u}Starting the ARCHandler@{ub}@{uu}
To be able to use the ARCHandler you should install it first. If you double
click  the  `Install'-icon,  the  handler  will  be  installed for you (the
installation  requires  the  Commodore Installer,
 Commodore). If you only
want  to  test  the  handler,  double  click the `ARC'-icon and a disk-icon
should appear on the Workbench-window named `Archives'.
Once  installed,  you'll  have to start the handler. If you've selected the
`Always  mount  ARC:  on  start-up?'-option  during  the  installation, the
handler  will  be started after each reset. If you did not use this option,
you'll have to start it manually:
under  Workbench  2.1 or higher the easiest way is to double-click the
   `ARC'-icon   in  the  `Storage/DOSDrivers'-drawer  of  your  Workbench
   partition (or disk);
if  you  are using  Workbench 2.04  or higher you can (also) start the
   handler by entering the following command in a Shell:
                               @{i}Mount ARC: @{ui}
If  everything  was  installed  correctly, a disk-icon should appear on the
Workbench-window   named  `Archives'  (or  the  name  you  selected  during
installation).
@endnode
@node using "ARCHandler: Using"
@next techno
@prev starting
  @{b}@{u}Using the ARCHandler@{ub}@{uu}
Once  the  ARCHandler is started, you should be able to use it as any-other
AmigaDOS-device.
The  root-directory  of  the  device contains all the volumes that AmigaDOS
knows  of  (it  even contains the ARC-volume, you can use this to access an
archive  in an archive). Just enter one of those volumes and you'll see all
the  files  and directories that are on that volume. You're able to use any
of these files the same way as on the normal volume, read a text, execute a
program (only read operations are supported in this version).
When  you  come  across an lha-archive you'll notice that the handler tells
you  that  it is a directory. When you enter the archive you'll see all the
files  and  directories that reside in the archive. These files can be used
as  normal files, you can read texts or execute the programs. Currently the
handler doesn't support writing to files in an archive.
@endnode
@node techno "ARCHandler: Technical Info"
@prev using
@next history
  @{b}@{u}Some technical background@{ub}@{uu}
  @{" Startup-arguments  " link startup}
  @{"  Workbench icons   " link icons}
  @{" Archive-file-lists " link filelists}
  @{"  FlushARC command  " link flusharc}
  @{"    Packet types    " link packets}
@endnode
@node startup "ARCHandler: Startup-arguments"
@prev startup
@next icons
@toc techno
  @{b}Startup-arguments@{ub}
The ARCHandler uses the `Startup'-field of a MountList/DOSDriver to let the
user  pass some important information. The string in the `Startup'-field is
parsed  with ReadArgs(). The string should always have double-quotes around
it  and  you should only use single-quotes (') in the string. Currently the
arc-handler recognizes the following arguments:
    @{" NAME       " link namearg}
    @{" LHA        " link lhaarg}
    @{" TEMPDIR    " link tempdirarg}
    @{" BUFFERS    " link buffersarg}
    @{" DISKICON   " link diskiconarg}
    @{" DRAWERICON " link drawericonarg}
    @{" NOEXTCHECK " link noextcheckarg}
The template of the `Startup'-field is:
  @{i}NAME/K,LHA/K,TEMPDIR/K,BUFFERS/K/N,DISKICON/K,DRAWERICON/K,NOEXTCHECK/S @{ui}
Example:
  Startup ="LHA=Work:C/LhA DISKICON='Work:Extra Icons/ARCDisk.info'"
NOTE:  The  `Install'  script  adds  a  `Startup'  tool  type  to  the
`ARC'-dosdriver-icon.  So,  if you want to change the `Startup'-field,
you  should  change the tool type (use the `Icons/Information...' menu
item of the Workbench)!
@endnode
@node namearg "ARCHandler: NAME argument"
@prev namearg
@next lhaarg
@toc startup
  @{u}NAME@{uu}
The  NAME  argument in the `Startup'-field of a MountList/DOSDriver is used
to  specify  the  name of the volume. You can specify any name you want, if
you  want  to  use spaces in the name surround the name with single-quotes.
The default name is `Archives'.
@endnode
@node lhaarg "ARCHandler: LHA argument"
@prev namearg
@next tempdirarg
@toc startup
  @{u}LHA@{uu}
The LHA argument in the `Startup'-field of a MountList/DOSDriver is used to
specify  the  place  of the `LhA'-command. You should specify the full path
(including  device/volume/assign).  If  the path contains spaces you should
surround the name with single-quotes. The default is `C:LhA'.
@endnode
@node tempdirarg "ARCHandler: TEMPDIR argument"
@prev lhaarg
@next buffersarg
@toc startup
  @{u}TEMPDIR@{uu}
The  TEMPDIR  argument  in  the  `Startup'-field  of  a MountList/DOSDriver
specifies  a directory where the ARCHandler can create its temporary files.
All  the  files  that the handler extracts from archives are placed in this
directory.  This  directory should be large enough to hold all those files.
You  should  specify the full path (including device/volume/assign). If the
path  contains  spaces you should surround the path with single-quotes. The
default is `T:'.
Special  note about MultiUser: don't use a directory on a muFS-partition as
the directory for temporary files!
@endnode
@node buffersarg "ARCHandler: BUFFERS argument"
@prev tempdirarg
@next diskiconarg
@toc startup
  @{u}BUFFERS@{uu}
The  BUFFERS  argument  in  the  `Startup'-field  of  a MountList/DOSDriver
indicates  the  number  of  unused  @{"archive-file-lists" link filelists} that the ARCHandler
keeps  in  memory.  This argument should be a number. The default number is
two and should probably not be changed.
@endnode
@node diskiconarg "ARCHandler: DISKICON argument"
@prev buffersarg
@next drawericonarg
@toc startup
  @{u}DISKICON@{uu}
With  the  DISKICON  argument you can specify the name of the icon that the
volume  should  use  as its disk-icon. This is the icon that appears in the
Workbench window. This arguments defaults to `DEVS:ARCDisk_info'.
Special  note  about  MultiUser:  don't  place  the  disk-icon  on  a muFS-
partition!
@endnode
@node drawericonarg "ARCHandler: DRAWERICON argument"
@prev diskiconarg
@next noextcheckarg
@toc startup
  @{u}DRAWERICON@{uu}
With the DRAWERICON argument you can specify the name of the icon that will
be used for the archives that are represented as directories. This argument
defaults to `DEVS:ARCDrawer_info'.
@endnode
@node noextcheckarg "ARCHandler: NOEXTCHECK argument"
@prev drawericonarg
@next noextcheckarg
@toc startup
  @{u}NOEXTCHECK@{uu}
ARCHandler  recognizes lha-archives by looking at the contents of the file.
Normally, the handler will only open (and thus recognize) files with a name
ending in `.lha' or `.lzh'.
When  you  specify  the  NOEXTCHECK  argument the handler will open all the
files  and  it  will  also recognize archives with a filename not ending in
`.lha'  or `.lzh'. However, this will take much longer to scan directories,
so  by  default the option is off (the argument is a switch, if you use the
argument in the `Startup'-field, the option is enabled).
@endnode
@node icons "ARCHandler: Workbench icons"
@prev startup
@next filelists
@toc techno
  @{b}Workbench icons@{ub}
To  be  able  to  easily  access  the ARCHandler through the Workbench, the
handler adds extra icons:
   -In  the  root  of  the  ARCHandler  volume  there  is  a disk-icon
    (Disk.info).  This  icon  is  currently  the only file that can be
    written to. (see also @{"DISKICON" link diskiconarg})
   -In  the  root  of  the  volume there are also drawer-icons for the
    other volumes. These icons are created from the original disk-icon
    on  that  volume  (if non disk-icon exists on a certain volume the
    default disk-icon will be used). You can't write to these icons.
   -For  all  the  archives  the  handler  recognizes a drawer-icon is
    added.   These   icons   are   also  write  protected.  (see  also
    @{"DRAWERICON" link drawericonarg})
@endnode
@node filelists "ARCHandler: Archive-file-lists"
@prev icons
@next flusharc
@toc techno
  @{b}Archive-file-lists@{ub}
ARCHandler  keeps  a certain amount of unused archive-file-lists (a list of
all the files and directories in an archive) in memory (@{"BUFFERS" link buffersarg}). This has
the  advantage  that the handler won't have to re-list the archive on every
access. This results in a faster response.
This also has a small side-effect, the handler keeps a lock on all archives
whose  archive-file-list  is still in memory. The handler uses a simple LRU
(least-recently-used) replacement rule to select the archive-file-list that
will be freed when another archive-file-list is no longer used. As a result
the  archive-file-list-lock  won't  be released until enough other archives
are used.
If,  at  a  certain  moment,  you want to free all unused archive-lists and
locks you can use the @{"FlushARC" link flusharc} command.
@endnode
@node flusharc "ARCHandler: FlushARC"
@prev filelists
@next packets
@toc techno
  @{b}FlushARC command@{ub}
You   can  use  the  FlushARC-command  if  you  want  to  free  all  unused
@{"archive-file-lists" link filelists}   and  archive-locks.  The  FlushARC  command  has  the
following template:
                              @{i}FlushARC DEVICE @{ui}
The  DEVICE  argument defaults to `ARC:'. The DEVICE argument should be the
name of the device, not the name of the volume.
To flush the device named `ARC2:' use:
                              @{i}FlushARC ARC2: @{ui}
@endnode
@node packets "ARCHandler: Packet types"
@prev flusharc
@next packets
@toc techno
  @{b}Unsupported packets@{ub}
This  is  a  list  of  the packets types that the handler currently doesn't
support:
    These actions will be supported in a future writable version:
      ACTION_CREATE_DIR
      ACTION_DELETE_OBJECT
      ACTION_RENAME_OBJECT
      ACTION_SET_COMMENT
      ACTION_SET_DATE
      ACTION_SET_FILE_SIZE
      ACTION_SET_PROTECT
    These   two  actions  don't  need to  be  implemented because  the
    dos.library  emulates  them  by  using  ACTION_EXAMINE_OBJECT  and
    ACTION_EXAMINE_NEXT:
      ACTION_EXAMINE_ALL
      ACTION_EXAMINE_ALL_END
    actions that may be implemented, if needed:
      ACTION_ADD_NOTIFY
      ACTION_CHANGE_MODE
      ACTION_COPY_DIR_FH
      ACTION_EXAMINE_FH
      ACTION_FH_FROM_LOCK
      ACTION_FREE_RECORD
      ACTION_LOCK_RECORD
      ACTION_MAKE_LINK
      ACTION_PARENT_FH
      ACTION_READ_LINK
      ACTION_REMOVE_NOTIFY
      ACTION_RENAME_DISK
      ACTION_SET_OWNER
    Actions that won't be implemented:
      ACTION_FORMAT
      ACTION_FLUSH
      ACTION_MORE_CACHE
      ACTION_INHIBIT
      ACTION_WRITE_PROTECT
  @{b}Packets ARCHandler needs@{ub}
This  is  the  minimal list of packets that an underlying FileSystem should
support, if you want to use it through the ARCHandler:
    ACTION_COPY_DIR
    ACTION_END
    ACTION_EXAMINE_NEXT
    ACTION_EXAMINE_OBJECT
    ACTION_FINDINPUT
    ACTION_FREE_LOCK
    ACTION_LOCATE_OBJECT
    ACTION_PARENT
    ACTION_READ
    ACTION_SEEK
@endnode
@node history "ARCHandler: History"
@prev techno
@next author
  @{b}@{u}History of the ARCHandler@{ub}@{uu}
 -----------------------------------------------------------------------
release 1.0 [37.129 (12.7.94)]
    -First release.
 -----------------------------------------------------------------------
release 1.0a [37.131 (14.7.94)]
    -Volumes  that  have  the  same  name as a device couldn't be used
     through the handler (reported by Erik Bergen).
    -Removed a nasty Enforcer hit.
    -Made some changes to the installation script.
 -----------------------------------------------------------------------
future release
    -Support for 2.0-packets.
    -Fully  writable  filesystem,  with  the ability to create/change
     files in archives.
    -Support for more archive types (zip/zoo/tar/...).
    -Support for packed files (XPK/PowerPacker/Imploder/...).
   These  are  just  some  of  the  features  I  @{i}might @{ui} add to a future
   release.  I  don't guarantee that either of these features will ever
   be  implemented (but I hope they will). If you've got any good ideas
   for a future release let @{"me" link author} know.
@endnode
@node author "About the Author"
@prev history
@next author
  ARCHandler was written by @{b}Rafael D'Halleweyn@{ub}.
If  you  have any questions, remarks, suggestions or bug reports please let
me  know.  You  can contact me via normal mail:
                            Rafael D'Halleweyn
                             Perckhoevelaan 17
                             B-2610 Antwerpen
                                  BELGIUM
Or you can try to reach me via EMail, you can reach me at:
                        [e-mail]
(but  this  is not my own account). I will try to read my mail there during
July, August and September. From October you'll be able to reach me at:
                        [e-mail]
(this is my own account).
      [if  you  only  have  fido-access you should send a message to
      UUCP  (2:29/777.0)  and  the  first line of the message should
      read `To: <fill in email address>',  the second line should be
      empty]
I'd  like  to  thank  Nico  Fran
ois,  Johan Billing, Per-Anders Josefsson,
Stefan  Zeiger,  Tom  De  Voeght and Peter Stuer for
eta-testing. I'd also
like  to thank David Larsson for the excellent KingCON. These seven persons
shouldn't  try to send me the shareware fee, because then I'll have to send
it back :-).
ARCHandler is Copyright
 Rafael D'Halleweyn. All Rights Reserved.
@endnode
@node index "ARCHandler: Index"
@prev index
@next index
  @{b}Index@{ub}
    @{"archive" link archive}
    @{"author" link author}
    @{"BUFFERS" link buffersarg}
    @{"Disclaimer" link disclaimer}
    @{"DISKICON" link diskiconarg}
    @{"DRAWERICON" link drawericonarg}
    @{"filelists" link filelists}
    @{"FlushARC" link flusharc}
    @{"history" link history}
    @{"icons" link icons}
    @{"Introduction" link introduction}
    @{"LhA" link lha}
    @{"LHA arguments" link lhaarg}
    @{"NAME" link namearg}
    @{"NOEXTCHECKARG" link noextcheckarg}
    @{"packets" link packets}
    @{"Requirements" link requirements}
    @{"Shareware" link shareware}
    @{"Starting" link starting}
    @{"Startup-field" link startup}
    @{"Technical Information" link techno}
    @{"TEMP" link tempdirarg
    @{"Using" link using}
    @{"Workbench icons" link icons}
@endnode